BITFIELDS

Section: Miscellaneous Library Functions (3X)
Updated: August 1, 1990
Index Return to Main Contents

NAME

bitfields - bit field manipulation library

SYNOPSIS

#include bitfields.f83

bitfields

DESCRIPTION

Allows definition and manipulation of bit fields. The bit field is described in a syntax similar to a structure with fields from the least significant bit towards the most significant bit. The bit field value is manipulated on the data stack and is therefore limited to the width of the stack, i.e., 32-bits. The kernel supports the bit field library with five functions; "b@", "b!", "f@", "<f@" and "f!". These allow high performance manipulation of stack oriented bit field data. The functions are also defined in forth for other environments.

vocabulary bitfields ( -- ): Vocabulary for bit field definitions. Include into the search path, "context", to allow definition and usage of the bit field library.
: bitfield.type ( -- ): Marks the beginning of a bit field type structure. Used in the following form:
bitfield.type <bitfield-type-name> ( -- )
{ <bitfield-name> }
bitfield.end
and to a create bit field variables:
<bitfield-type-name> <bitfield-variable-name> ( -- addr)
The bits within the bit field are numbered from 0 to 31 starting from right (lsb) to left (msb). The <bitfield-name> may be generated with the words "bit", "bits", "byte", "nibble", and, "word" to define the bit field names.
: bits ( width -- ): Used in the following form:
<width> bits <bitfield-name> ( -- pos width)
within a bit field type definition to define field name for an arbitrary set of bits.
bitfield.field bit ( -- ): Used in the following form:
bit <bitfield-name> ( -- pos width)
within a bit field type layout definition section to give name to a bit at the current position. The bit positions are numbered from 0 to 31 and right to left within a long number.
bitfield.field nibble ( -- ): Used in the following form:
nibble <bitfield-name> ( -- pos width)
within a bit field type layout section definition to give name to a nibble (four bits).
bitfield.field byte ( -- ): Used in the following form:
byte <bitfield-name> ( -- pos width)
within a bit field type layout section definition to give name to a byte (eight bits).
bitfield.field word ( -- ): Used in the following form:
word <bitfield-name> ( -- pos width)
within a bit field type layout section definition to give name to a word (sixteen bits).
: bitfield.end ( -- ): Ends the definition of a bit field type. Will give a warning message if the last field position exceeded 32 bits.

INTERNALS

The bitfields vocabulary contains the following private definitions to allow definition of fields.

: bitfield.field ( width -- ) private: Utility function to create additional constant bit field type names, other than "bit", "byte", etc.

EXAMPLES

To create an object pointer bit field structure with fields for type and pointer:

#include bitfields.f83
#include enumerates.f83

bitfields enumerates

bitfield.type OBJECT ( -- )
        2  bits TYPE ( -- pos width)
        30 bits VALUE ( -- pos width)
bitfield.end

Create an object pointer, access and manipulate its value:

enum.type PRIMITIVE-CLASS ( -- )
        enum SMALL-NUMBER ( -- enum)
        enum BLOCK-POINTER ( -- enum)
        enum OBJECT-HANDLE ( -- enum)
        enum PRIMITIVE ( -- enum)
enum.end

OBJECT x ( -- addr)

SMALL-NUMBER 0 TYPE f! ( -- 0 | SMALL-NUMBER)
42 swap VALUE f! ( -- 42 | SMALL-NUMBER)
x !

NOTE

The function list is sorted in logical order.
The type and mode of the entries are indicated together with their parameter stack effect.

The bit field definitions require a 32-bit cell size. This library may only be directly ported to other 32-bit implementations of the Forth-83 Standard.

COPYING

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English.

AUTHOR

Mikael R.K. Patel
Computer Aided Design Laboratory (CADLAB)
Department of Computer and Information Science
Linkoping University
S-581 83 LINKOPING
SWEDEN
Email: mip@ida.liu.se

This document was created by man2html, using the manual pages.
Time: 17:16:17 GMT, February 06, 2023